\documentclass[a4paper,10pt]{scrartcl}
%\documentclass[a4paper,10pt]{article}


\usepackage{hyperref}
\usepackage{longtable}
\usepackage{amsmath}
\usepackage{booktabs}
\usepackage{graphicx}

% 
%opening
%\title{}
%\author{}


\begin{document}


\parindent 0pt
\parskip 10pt
\setlength{\textheight}{22cm}
%\setlength{\textwidth}{20cm}
\setlength{\headheight}{0.2cm}


\hspace{16cm}
\section*{\centering \huge SHOREmap Manual}
\setcounter{section}{0}
\vspace{.4cm}
\begin{center}
Version 1.1\\[1cm]

Stephan Ossowski\\
Korbinian Schneeberger\\[1cm]


@ Max Planck Institute for Developmental Biology\\
T\"ubingen, Weigelworld, 26.03.2009\\
\end{center}


\newpage
\vspace{.4cm}
\tableofcontents

\newpage

\vspace{.5cm}

SHOREmap is an analysis pipeline for mapping and mutant identification in one step. See "SHOREmap: simultaneous mapping and mutation identification by deep sequencing", Schneeberger, Ossowski et al., Nat Meth, 2009, for further information about the application of SHOREmap.

In order to run SHOREmap you need to provide the output of a Next Generation Sequencing read analysis in the right format. SHORE, a short read analysis tool, provides correctly formatted files. However, any alignment tool can be used, if its output is formatted in the right way for SHOREmap.

Find a detailed description of how to use SHORE in the SHORE-README file on http://1001genomes.org/downloads.

Korbinian Schneeberger and Stephan Ossowski, T\"ubingen, March 2009

This is version is updated in order to work with SHORE version 0.4 and higher.

\newpage

\section{Prerequisites}
\subsection{Download and Installation}

Download SHORE and SHOREmap from http://1001genomes.org/downloads/shore. After storing the SHOREmap\_release\_1.0.tar.gz somewhere on your harddrive, use the terminal application and change the working directory to the directory where you stored SHOREmap. Typing

\begin{verbatim}
tar zxf SHOREmap_release_1.1.tar.gz
\end{verbatim}

will unpack SHOREmap. There is no further need for installing.

\subsection{Installation of R}

SHORE and SHOREmap make use of R for data visualization. Where R is not necessary for SHORE, it becomes necessary for SHOREmap. R has to be installed and the installation path has to be added to the \$PATH environmental variable.\\

\subsection{Installation of PERL and BioPerl}

SHOREmap is written in PERL. To run SHOREmap you need to have PERL and BioPerl installed on your computer.

\newpage
\section{SHOREmap Guide}

\subsection{SHOREmap\_interval.pl}

INTERVAL generates a visual output allowing the user to define a mapping interval. By default INTERVAL prints out 10 different plots of all chromosomes, each with a different sliding window size. After inspecting these plots, the user selects one of them and uses the text file associated with it as input for ANNOTATE. It is not critical to select the smallest possible interval, the only requirement is that the highest peak must be included within the selected region. This peak is used by ANNOTATE to prioritize the mutations within the interval.
If the first set of plots is not satisfying, e.g. too flattened or too jagged, we recommend re-running INTERVAL with a new set of sliding window sizes.

Example:

\begin{verbatim}
> SHOREmap_interval.pl --consensus=consensus_summary.txt 
--marker=marker.txt --chrsizes=chrsizes.txt --referrors=ref_error.txt
\end{verbatim}

-consensus describes the base count per position and is calculated by SHORE. -marker lists the marker positions. -chrsizes indicates the length of each reference sequence, which is necessary for a uniform plotting of the chromosomes. -referrors describes all the positions that will be disgarded by INTERVAL.

Not used in this example: -windowstep describes the number of bp between the reported data points. Usually you do not have to change this. -windowsize might be adjusted once the first round of interval finding has been analyzed.

\subsection{SHOREmap\_annotate.pl}

ANNOTATE outputs a list of mutations prioiritized by their distance to the highest peak in the user-defined interval (either generated by INTERVAL or by DENOVO). If additional information about gene annotations is provided (in GFF format) the effect of the mutations will be added to the output.

Example:

\begin{verbatim}
> SHOREmap_annotate.pl --snp=homozygous_snps.txt 
--dist=SHOREmap.output.txt --chrom=4 --start=16000000 
--end=17000000 --genome=TAIR8.v1.fa --gff=TAIR8.gff 
--referr=ref_error.txt
\end{verbatim}

-snp describes all mutations called, in SHORE format. -dist is the output file of either INTERVAL or DENOVO. -chrom, -start and -end indicate the interval location. -genome is the reference sequence in fasta format. -gff is a GFF formatted description of the reference annotation. -referr describes all the positions, which will be disgarded in the final output.

Not used in this example: -del and -ins describe small indels found in the read mapping which could of course also be causal for the selected phenotype. Files are in SHORE format.

\subsection{SHOREmap\_denovo.pl}

Like INTERVAL, DENOVO helps defining the mapping interval, but does not rely on knowledge of marker postions. Instead markers are defined on the fly as heterozygous positions in the short read data. DENOVO detects the heterozygous positions based on the read alignments and calculates their frequencies and the distance of each postion to the next marker. This is based on the assumption that the homozygous character of the genomic region harboring the causal mutation reduces the density of markers and thus increases the average distance to the nearest marker.

Different to INTERVAL, only one plot is generated. Multiple run of DENOVO will allow the user to select one of the plots and to define an interval based on the peak location. The text file associated with the selected plot is then used as input for ANNOTATE. 

Example:

\begin{verbatim}
> SHOREmap_denovo.pl --snp=minor_allele_frequency.txt 
--refseq=reference.txt --chrsizes=chrsizes.txt
\end{verbatim}

-snp describes the base counts of the short read data (not to be confused with the snp file in ANNOTATE). -refseq lists the positions with significant support for the reference base. This information is used as a measure for the callability of regions. -chrsizes indicates the length of each of the reference sequences, which is necessary for a uniform plotting of the chromosomes.

Not used in this example: -support minimum read support for both of the alleles at a single position to be considered as a het call. This depends on the coverage, usually 2 to 4 should work. -freq same as -support though this time independent of the absolute read alignments at this position. -winsize has to be adjusted and probably run multiple times with different settings in order to get a broad view of the outcome of different window sizes, also in combination with different adjustments of -freq and -support.

\section{File formats}

All columns described for all file formats have to be tab delimited. The number at the begining of a column description indicates the column number within the respective file format. Since we use the standard SHORE output as input for SHOREmap, some file formats feature columns not used in SHOREmap.

\subsection{Input files}

\subsubsection{Consensus file (INTERVAL)}

Summary of the read alignments. \"consensus\_summary.txt\" in the SHORE output. We have to admit that it is unfortunate that the columns used are scattered throughout the file. However, by simply using SHORE as the short read analysis tool the user will not have any file format issues.

1: $<$chromosome$>$ Chromosome identifier\\
2: $<$position$>$ Position of a base in the reference sequence\\
4: $<$coverage$>$ Number of alignments overlapping this position\\
5: $<$A$>$ Number of A overlapping this position\\
6: $<$C$>$ Number of C overlapping this position\\
7: $<$G$>$ Number of G overlapping this position\\
8: $<$T$>$ Number of T overlapping this position\\
61: $<$ref base$>$ Base in the reference sequence\\

\subsubsection{Marker file (INTERVAL)}

1: $<$chromosome$>$ Chromosome identifier\\
2: $<$position$>$ Position of a base in the reference sequence\\
4: $<$SNP base$>$ Marker allele different to the reference base\\

\subsubsection{Chromosome sizes (INTERVAL, DENOVO)}

1: $<$chromosome$>$ Chromosome identifier\\
2: $<$size$>$ Chromosome size\\

\subsubsection{Reference errors (INTERVAL, ANNOTATE)}

1: $<$chromosome$>$ Chromosome identifier\\
2: $<$position$>$ Position of a reference error\\

\subsubsection{Homozygous SNPs (ANNOTATE)}

See the SHORE manual for descrition for \"homozygous\_snps.txt\".

\subsubsection{Genome (ANNOTATE)}

Fasta file of the reference sequence.

\subsubsection{Annotation GFF (ANNOTATE)}

See the general description of GFF files.

\subsubsection{Minor alleles (DONOVO)}

See the SHORE manual for description of \"minor\_allele\_positions.txt\".

\subsubsection{Reference calls (DONOVO)}

See the SHORE manual for description of \"reference.txt\".

\subsection{Output files}

\subsubsection{Prioritized SNP list (ANNOTATE)}

1: $<$chromosome$>$ Chromosome identifier\\
2: $<$position$>$ Position of a base in the reference sequence\\
3: $<$ref base$>$ Base in the reference sequence\\
4: $<$mut base$>$ Mutation\\
5: $<$Distance$>$ Number of bp to the peak in the interval\\
6: $<$Support$>$ Number of reads supporting the base change\\
7: $<$Concordance$>$ Concordance of the short reads overlapping the position\\
8: $<$Quality$>$ Highest base quality supporting the base change\\
9: $<$Type$>$ Either NEWSNP or REFERR\\
10: $<$SeqType$>$ Type of the DNA which is affected of the change\\
11: $<$ID$>$ Gene identifier\\
12: $<$Isoform$>$ Isoform of the gene\\
13: $<$Codon pos$>$ Coding sequence position of the change\\
14: $<$Codon pos$>$ Codon position of the change\\
15: $<$AA type$>$ Either Syn or Nonsyn\\
16: $<$Ref AA$>$ Amino acid of the reference\\
17: $<$Mut AA$>$ Amino acid after base change\\

\newpage

We appreciate any kind of feedback.
Please do not hesitate to contact us in case of any problems or questions.

Korbinian Schneeberger $<$korbinian.schneeberger@tuebingen.mpg.de$>$\\
Stephan Ossowski $<$stephan.ossowski@tuebingen.mpg.de$>$\\

\end{document}

